.TH VNSTAT.CONF 5 "SEPTEMBER 2025" "version 2.14" "User Manuals"
.SH NAME
vnstat.conf \- vnStat configuration file

.SH SYNOPSIS

.B /etc/vnstat.conf

.SH DESCRIPTION

.BR vnstat (1),
.BR vnstati (1)
and
.BR vnstatd (8)
all use the same configuration file for configuration related settings.
Some of the settings are common for all three programs. The file
consists of keyword-argument pairs, one per line. Empty lines and
lines starting with '#' or ';' are interpreted as comments and not processed.
Arguments may optionally be enclosed in double quotes (") in order
to represent arguments containing spaces. Arguments can be padded
with spaces or tabulator characters. A hardcoded default value
will be used if a keyword can't be found from the configuration file or
if the configured value cannot be parsed or is outside supported value range.
.PP
The configuration file is divided into three sections based on the
usage of each keyword. The first section contains keywords that are
considered common for all commands, the second section is for
daemon related keywords and the last section is for image output.

.SH COMMON KEYWORDS

.TP
.B DatabaseDir
Specifies the directory where the database is to be stored.
A full path must be given and a leading '/' isn't required.

.TP
.B "DayFormat, MonthFormat, TopFormat"
Formatting of date in available outputs. Uses the same format as
.BR date (1).
(vnstat and vnstati only)

.TP
.B DefaultDecimals
Number of decimals to use in outputs. Value range: 0..2
(vnstat and vnstati only)

.TP
.B EstimateBarVisible
Show a visual representation of the traffic estimation if
.B OutputStyle
has been configured with a value of 1 or 2 to make the bar column visible.
1 = enabled, 0 = disabled.
(vnstat only, see
.B EstimateStyle
for vnstati)

.TP
.B EstimateText
Replace default "estimated" text on the estimate line with custom text.
Limited to 9 characters. (vnstat and vnstati only)

.TP
.B EstimateVisible
Show a line with traffic estimation for the selected time period or alert as the
last line of the output in output modes supporting it. Disabling estimate visibility
also disables estimate conditions in
.BR "--alert" "."
1 = enabled, 0 = disabled. (vnstat and vnstati only)

.TP
.B HourlyDecimals
Number of decimals to use in hourly graph output. Value range: 0..2
(vnstat only)

.TP
.B HourlySectionStyle
Select what kind of spacer is used for separating the numerical sections of the
hourly graph output. 0 = none, 1 = '|', 2 = '][', 3 = '[ ]'.
(vnstat only)

.TP
.B Interface
Default interface used when no other interface is specified on the command
line. Leave empty for automatic selection. The automatic selection will
prioritize the interface with most traffic for outputs doing database queries.
Queries not using the database will first check if the database is available
and select the interface with most traffic out those that are currently
visible in the system. If no database can be read then the first available
interface will be used. (vnstat and vnstati only)

.TP
.B InterfaceMatchMethod
Method for matching interface given for a query to an interface in the
database.

Method 0 requires the interface name to be a case sensitive exact
match. Method 1 extends the previous method by allowing a case sensitive
exact match of the interface alias. Method 2 extends the previous method
by allowing a case insensitive exact match of the interface alias. Method
3 extends the previous method by allowing a case insensitive match of the
beginning of the interface alias.

Methods will be evaluated in the order described above resulting in exact
interface matches always taking precedence. If any interface alias matching
method results in multiple matches then the interface with the highest total
traffic will be used. (vnstat and vnstati only)

.TP
.B InterfaceOrder
Interface order in outputs with multiple interfaces. 0 = alphabetical
by name, 1 = alphabetical by alias. If 1 is selected and multiple interfaces
don't have aliases then the interface name will be used for defining the order.
(vnstat only)

.TP
.B "List5Mins, ListHours, ListDays, ListMonths, ListYears, ListTop"
Number of entries to show in list outputs unless overridden from the command line.
Set to 0 to show all entries available in the database.
(vnstat and vnstati)

.TP
.B LiveSpinner
Show spinning animation at the beginning of
.BR "-l" " /"
.B "--live"
output line. 1 = enabled, 0 = disabled. (vnstat only)

.TP
.B Locale
Locale setting to be used for prints. This replaces the LC_ALL
environment variable. Set to "-" or leave empty in order to use the
system default value. (vnstat and vnstati only)

.TP
.B OutputStyle
Modify the content and style of text outputs. 0 = minimal and
narrow output for terminal with limited width, 1 = normal output with
bar column visible, 2 = same as 1 except rate is visible in summary
output, 3 = rate column is visible in all outputs where it is supported.
(vnstat and vnstati only)

.TP
.B QueryMode
Default query mode when no parameters are given. 0 = summary, 1 = days,
2 = months, 3 = top, 4 = single summary, 5 = short, 6 = years, 7 = hours graph,
8 = xml, 9 = one line, 10 = json, 11 = hours and 12 = 5 minute. (vnstat only)

.TP
.B RateUnit
Select which unit is used when traffic rate is visible. 0 = bytes, 1 = bits.
(vnstat and vnstati only)

.TP
.B RateUnitMode
Select used prefix when traffic rate is shown in bits per second.
IEC binary prefixes are calculated with powers of 1024. SI decimal
prefixes are calculated with powers of 1000.
0 = IEC binary prefixes (Kibit/s...), 1 = SI decimal prefixes (kbit/s...).
(vnstat and vnstati only)

.TP
.B "RXCharacter, TXCharacter"
Character used for representing the percentual share of received
and transmitted traffic in list mode outputs. (vnstat only)

.TP
.B "RXHourCharacter, TXHourCharacter"
Character used for representing the percentual share of received
and transmitted traffic in hourly graph output. (vnstat only)

.TP
.B Sampletime
Defines how many seconds the
.B "-tr"
option will sample traffic. Value range: 2..600 (vnstat only)

.TP
.B UnitMode
Select how units are prefixed. IEC and JEDEC binary prefixes are calculated
with powers of 1024. SI decimal prefixes are calculated with powers of 1000.
0 = IEC standard prefixes (B/KiB/MiB/GiB...), 1 = old style (JEDEC)
binary prefixes (B/KB/MB/GB...), 2 = SI decimals prefixes (B/kB/MB/GB...)
(vnstat and vnstati only)

.SH DAEMON RELATED KEYWORDS

.TP
.B 5MinuteHours
Data retention duration for the 5 minute resolution entries. The configuration
defines for how many past hours entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.TP
.B 64bitInterfaceCounters
Select interface counter handling. Set to 1 for defining that all interfaces
use 64-bit counters on the kernel side and 0 for defining 32-bit counter. Set
to -1 for using the old style logic used in earlier versions where counter
values within 32-bits are assumed to be 32-bit and anything larger is assumed to
be a 64-bit counter. This may produce false results if a 64-bit counter is
reset within the 32-bits. Set to -2 for using automatic detection based on
available kernel datastructures.

.TP
.B AlwaysAddNewInterfaces
Enable or disable automatic creation of new database entries for interfaces not
currently in the database even if the database file already exists when the
daemon is started. New database entries will also get created for new interfaces
seen while the daemon is running. Pseudo interfaces lo, lo0 and sit0 are always
excluded from getting added.
1 = enabled, 0 = disabled.

.TP
.B BandwidthDetection
Try to automatically detect
.B MaxBandwidth
value for each monitored interface. Mostly only ethernet interfaces support
this feature.
.B MaxBandwidth
will be used as fallback value if detection fails. Any interface specific
.B MaxBW
configuration will disable the detection for the specified interface.
In Linux, the detection is disabled for tun interfaces due to the
Linux kernel always reporting 10 Mbit regardless of the used real interface.
1 = enabled, 0 = disabled.

.TP
.B BandwidthDetectionInterval
How often in minutes interface specific detection of
.B MaxBandwidth
is done for detecting possible changes when
.B BandwidthDetection
is enabled. Can be disabled by setting to 0. Value range: 0..30

.TP
.B BootVariation
Time in seconds how much the boot time reported by system kernel can variate
between updates. Value range: 0..300

.TP
.B CheckDiskSpace
Enable or disable the availability check of at least some free disk space before
a database write. 1 = enabled, 0 = disabled.

.TP
.B CreateDirs
Enable or disable the creation of directories when a configured path doesn't
exist. This includes
.B DatabaseDir
,
.B LogFile
and
.B PidFile
directories. The
.B LogFile
directory will be created only when
.B UseLogging
has been set to 1. The
.B PidFile
directory will be created only if the daemon is started as a background process.
The daemon process will try to create the directory using permissions of the
user used to start the process.

.TP
.B DaemonGroup
Specify the group to which the daemon process should switch during startup.
The group can either be the name of the group or a numerical group id.
Leave empty to disable group switching. This option can only be used when
the process is started as root.

.TP
.B DaemonUser
Specify the user to which the daemon process should switch during startup.
The user can either be the login of the user or a numerical user id.
Leave empty to disable user switching. This option can only be used when
the process is started as root.

.TP
.B DailyDays
Data retention duration for the one day resolution entries. The configuration
defines for how many past days entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.TP
.B DatabaseSynchronous
Change the setting of the SQLite "synchronous" flag which controls how much
care is taken to ensure disk writes have fully completed when writing data to
the database before continuing other actions. Higher values take extra steps
to ensure data safety at the cost of slower performance. A value of 0 will
result in all handling being left to the filesystem itself. Set to -1 to
select the default value according to database mode controlled by
.B DatabaseWriteAheadLogging
setting. See SQLite documentation for more details regarding values from 1
to 3. Value range: -1..3

.TP
.B DatabaseWriteAheadLogging
Enable or disable SQLite Write-Ahead Logging mode for the database. See SQLite
documentation for more details and note that support for read-only operations
isn't available in older SQLite versions. 1 = enabled, 0 = disabled.

.TP
.B HourlyDays
Data retention duration for the one hour resolution entries. The configuration
defines for how many past days entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.TP
.B LogFile
Specify log file path and name to be used if UseLogging is set to 1.

.TP
.B MaxBandwidth
Maximum bandwidth for all interfaces. If the interface specific traffic
exceeds the given value then the data is assumed to be invalid and rejected.
Set to 0 in order to disable the feature. Value range: 0..50000

.TP
.B MaxBW
Same as
.B MaxBandwidth
but can be used for setting individual limits
for selected interfaces. The name of the interface is specified directly
after the MaxBW keyword without spaces. For example MaxBWeth0 for eth0
and MaxBWppp0 for ppp0.
.B BandwidthDetection
is disabled on an interface specific level for each
.B MaxBW
configuration. Value range: 0..50000

.TP
.B MonthlyMonths
Data retention duration for the one month resolution entries. The configuration
defines for how many past months entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.TP
.B MonthRotate
Day of month that months are expected to change. Usually set to
1 but can be set to alternative values for example for tracking
monthly billed traffic where the billing period doesn't start on
the first day. For example, if set to 7, days of February up to and
including the 6th will count for January. Changing this option will
not cause existing data to be recalculated. Value range: 1..28

.TP
.B MonthRotateAffectsYears
Enable or disable
.B MonthRotate
also affecting yearly data. Applicable only when
.B MonthRotate
has a value greater than one. 1 = enabled, 0 = disabled.

.TP
.B OfflineSaveInterval
How often in minutes cached interface data is saved to file when all monitored
interfaces are offline. Value range:
.BR SaveInterval "..60"

.TP
.B PidFile
Specify pid file path and name to be used. The file is created only if the
daemon is started as a background process.

.TP
.B PollInterval
How often in seconds interfaces are checked for status changes.
Value range: 2..60

.TP
.B RescanDatabaseOnSave
Automatically discover added interfaces from the database and start monitoring.
The rescan is done every
.B SaveInterval
or
.B OfflineSaveInterval
minutes depending on the current activity state.
1 = enabled, 0 = disabled.

.TP
.B SaveInterval
How often in minutes cached interface data is saved to file.
Value range: (
.BR UpdateInterval " / 60 )..60"

.TP
.B SaveOnStatusChange
Enable or disable the additional saving to file of cached interface data
when the availability of an interface changes, i.e., when an interface goes
offline or comes online. 1 = enabled, 0 = disabled.

.TP
.B TimeSyncWait
How many minutes to wait during daemon startup for system clock to sync if
most recent database update appears to be in the future. This may be needed
in systems without a real-time clock (RTC) which require some time after boot
to query and set the correct time. 0 = wait disabled.
Value range: 0..60

.TP
.B TopDayEntries
Data retention duration for the top day entries. The configuration
defines how many of the past top day entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.TP
.B TrafficlessEntries
Create database entries even when there is no traffic during the entry's time
period. 1 = enabled, 0 = disabled.

.TP
.B UpdateFileOwner
Enable or disable the update of file ownership during daemon process startup.
During daemon startup, only database, log and pid files will be modified if the
user or group change feature (
.B DaemonUser
or
.B DaemonGroup
) is enabled and the files don't match the requested user or group. During manual
database creation, this option will cause file ownership to be inherited from the
database directory if the directory already exists. This option only has effect
when the process is started as root or via sudo.

.TP
.B UpdateInterval
How often in seconds the interface data is updated. Value range:
.BR PollInterval "..300"

.TP
.B UseLogging
Enable or disable logging. This option is ignored when the daemon is started with
.B "-n, --nodaemon"
which results in all log output being shown in terminal the daemon process is using.
0 = disabled, 1 = logfile and 2 = syslog.

.TP
.B UseUTC
Enable or disable using UTC as timezone in the database for all entries. When
enabled, all entries added to the database will use UTC regardless of the
configured system timezone. When disabled, the configured system timezone
will be used. Changing this setting will not result in already existing
data to be modified. 1 = enabled, 0 = disabled.

.TP
.B VacuumOnHUPSignal
Enable or disable the execution of SQLite VACUUM command after the daemon has received
a HUP signal. When enabled, the database file is rebuilt and repacked into a minimal amount
of disk space. The difference in size can be notable especially if data retention
durations have been reduced or previously monitored interfaces removed from the database.
1 = enabled, 0 = disabled.

.TP
.B VacuumOnStartup
Enable or disable the execution of SQLite VACUUM command during daemon startup.
When enabled, the database file is rebuilt and repacked into a minimal amount
of disk space. The difference in size can be notable especially if data retention
durations have been reduced or previously monitored interfaces removed from the database.
1 = enabled, 0 = disabled.

.TP
.B YearlyYears
Data retention duration for the one year resolution entries. The configuration
defines for how many past years entries will be stored. Set to -1 for
unlimited entries or to 0 to disable the data collection of this
resolution.

.SH IMAGE OUTPUT RELATED KEYWORDS

.TP
.B 5MinuteGraphResultCount
Number of 5 minute periods to be included in the 5 minute resolution graph.
The value affects the width of the graph. Value range: 288..2000

.TP
.B 5MinuteGraphHeight
Height of 5 minute resolution graph in pixels. Value range: 150..2000

.TP
.B BarColumnShowsRate
The bar column represents traffic rate in list outputs when enabled. Requires
also that
.B OutputStyle
has been configured to show the traffic rate column by using the value 3.
Enabling this option will automatically cause
.B EstimateStyle
to have the value 0. Visually this option affects only the color legend text and
the last line on the list if that line represents the currently ongoing time
period. 1 = enabled, 0 = disabled.

.TP
.B CBackground
Background color.

.TP
.B CEdge
Edge color, if visible.

.TP
.B CHeader
Header background color.

.TP
.B CHeaderTitle
Header title text color.

.TP
.B CHeaderDate
Header date text color.

.TP
.B CLine
Line color.

.TP
.B CLineL
Lighter version of line color. Set to '-' in order to use a calculated
value based on
.BR CLine .

.TP
.B CPercentileLine
95th percentile line color. Used only in 95th percentile graph.

.TP
.B CRx
Color for received data.

.TP
.B CRxD
Darker version of received data color. Set to '-' in order to use
a calculated value based on
.BR CRx .

.TP
.B CText
Common text color.

.TP
.B CTotal
Color for total data, sum of received and transmitted data.
Used only in 95th percentile graph.

.TP
.B CTx
Color for transmitted data.

.TP
.B CTxD
Darker version of transmitted data color. Set to '-' in order to use
a calculated value based on
.BR CTx .

.TP
.B EstimateStyle
Show a visual representation of the traffic estimation.
0 = not shown, 1 = continuation of existing bar, 2 = separate bar.

.TP
.B HeaderFormat
Formatting of date in header. Uses the same format as
.BR date (1).

.TP
.B HourlyGraphMode
Select the output mode of the hourly graph. 0 = 24 hour sliding window,
1 = graph begins from midnight.

.TP
.B HourlyRate
Show hours with rate instead of transferred amount. 1 = enabled, 0 = disabled.

.TP
.B ImageScale
Scale output to given percent. Value range: 50..500

.TP
.B LargeFonts
Increase the size of used fonts. 1 = enabled, 0 = disabled.

.TP
.B LineSpacingAdjustment
Adjust line spacing in list format outputs. Positive values increase the
space between lines while negative values reduce it. Value range: -5..10

.TP
.B SummaryGraph
Select which graph style output is shown next to the summary data in the
horizontal and vertical summary outputs. 0 = hours, 1 = 5 minutes.

.TP
.B SummaryRate
Show rate in summary output if available. 1 = enabled, 0 = disabled.

.TP
.B TransparentBg
Set background color as transparent. 1 = enabled, 0 = disabled.

.SH FILES

.TP
.I $XDG_CONFIG_HOME/vnstat/vnstat.conf
1st option if not overridden using a command line parameter.

.TP
.I $HOME/.config/vnstat/vnstat.conf
2nd option if not overridden using a command line parameter.

.TP
.I $HOME/.vnstatrc
3rd option if not overridden using a command line parameter.

.TP
.I /etc/vnstat.conf
4th option if not overridden using a command line parameter.

.TP
.I /usr/local/etc/vnstat.conf
5th option if not overridden using a command line parameter.

.SH RESTRICTIONS

Using long date output formats may cause misalignment in shown columns if the
length of the date exceeds the fixed size allocation.

.SH AUTHOR

Teemu Toivola <tst at iki dot fi>

.SH "SEE ALSO"

.BR vnstat (1),
.BR vnstati (1),
.BR vnstatd (8),
.BR units (7)
